Skip to content

refactor(docs): consume layer plumbing instead of forking it - #330

Merged
alexgrozav merged 3 commits into
mainfrom
agent/signal/31246d31
Aug 6, 2026
Merged

alexgrozav merged 3 commits into
mainfrom
agent/signal/31246d31

Conversation

@alexgrozav

Copy link
Copy Markdown
Contributor

Summary

@uxfront/layer-docs now ships the plumbing this app was forking. Deletes the forks. Net -2150 lines.

Companion to uxfront-com/uxfront#56. Sub-issue of UXF-3 (layer/app boundary audit).

Important

Blocked on release. This pins @uxfront/layer-docs@^0.2.0, which is not published yet. uxfront#56 must merge and publish first, then pnpm-lock.yaml regenerates. Draft until then.

What went away

  • content.config.ts: 118 lines → 11. defineDocsCollections(DOCS_SECTIONS, { sitemap: true, changelog: true }). Section topology stays local in app/constants/sections.ts; collection shapes, per-locale fan-out and schemas come from the layer.
  • i18n/locales/ (31 files), nuxt.schema.ts, modules/optimizeDeps.ts, modules/useDocusI18nOverride.ts. That last module's own docblock said to delete it once the package shipped its locales — it does now.
  • 18 shadow copies that re-declared layer files at the same relative path. Layer precedence meant every upstream fix to those files was invisible here. Most visibly, the AppHeader anchor-nesting a11y fix is now actually in effect — verified against the prerendered HTML: max anchor nesting depth in <header> is 1.
  • utils/prerender.ts — the layer's app/utils/prerender.ts is equivalent and auto-imported, so the explicit ../../../../../utils/prerender import goes too.

What arrived

app.config.ts declares docsTheme.frameworks — React / Vanilla / Vue, order preserved from the deleted DEFAULT_FRAMEWORKS. The layer no longer ships a default list (which frameworks a site documents is a site fact), so this array is now the only source.

Shadows kept, deliberately

Each now carries a docblock naming its delta and its deletion trigger:

File Delta Deletes when
app/composables/useDocsSections.ts THEME_SUBSECTIONS split — a styleframe content shape the content shape flattens
app/components/docs/DocsAsideLeftBody.vue theme-subsection nav filter + ProIcon badge same
app/pages/[[lang]]/[...slug].vue defineOgImage OG image support lands in the layer (UXF-3 #4)
app/pages/[[lang]]/docs/[section]/[...slug].vue defineOgImage same
app/types/non-route-categories.ts duplicate of the layer's copy modules/nonRouteCategories.ts moves into the layer (UXF-3 #5)

Two of these were rebased onto the layer copy, picking up fixes they had been shadowing:

  • useDocsSections.ts gained the missing hasSectionSwitcher. Without it the layer's AppSubHeader read undefined and the docs sub-header never rendered — a live bug this PR fixes as a side effect.
  • The docs page took the layer's <USeparator decorative> a11y fix (a separator role with focusable descendants is a nested-interactive violation).

Test plan

Verified against a packed tarball of uxfront#56 (npm pack + pnpm.overrides file:), since 0.2.0 isn't on npm yet. The override was reverted before committing — the diff here contains no local-path scaffolding.

  • nuxt prepare — clean, types generated.
  • pnpm build — Build complete, 60.5 MB. No errors (sourcemap/sharp warnings only).
  • Prerender — 705 routes in 44s; 174 HTML pages on disk (autoSubfolderIndex: false, so routes emit as <path>.html).
  • pnpm test — 3 passed. pnpm test:build — 2 passed. Brand-palette guardrails hold.
  • oxlint apps/docs clean; oxfmt --check clean over 36 files.
  • AppHeader anchor-nesting fix confirmed live in .output/public/index.html.

`@uxfront/layer-docs` now ships the collections builder options, the
locale files, the Content Studio schema and the Vite prebundle hints, so
the local forks are dead weight. Net -2150 lines.

- `content.config.ts`: 118 lines -> 11. `defineDocsCollections(DOCS_SECTIONS,
  { sitemap: true, changelog: true })`. Section topology stays local in
  `app/constants/sections.ts`; the collection shapes, per-locale fan-out and
  schemas come from the layer.
- Deleted `i18n/locales/` (31 files), `nuxt.schema.ts`,
  `modules/optimizeDeps.ts` and `modules/useDocusI18nOverride.ts`. That
  module's own docblock said to remove it once the package shipped its
  locales; it does now.
- Deleted 18 shadow copies that re-declared layer files at the same relative
  path. Layer precedence meant every upstream fix to those files was
  invisible here — notably the `AppHeader` anchor-nesting a11y fix, which is
  now actually in effect (verified: max anchor nesting depth 1 in the
  prerendered header).
- Deleted `utils/prerender.ts`; the layer's `app/utils/prerender.ts` is
  equivalent and auto-imported, so the explicit relative import goes too.
- `app.config.ts` declares `docsTheme.frameworks` (React/Vanilla/Vue, order
  preserved). The layer no longer ships a default list.

Four shadows are kept deliberately, each now carrying a docblock naming its
delta and its deletion trigger:

- `useDocsSections.ts` — the `THEME_SUBSECTIONS` split is a styleframe
  content shape. Rebased onto the layer copy, which adds the missing
  `hasSectionSwitcher`; without it the layer's `AppSubHeader` read
  `undefined` and the docs sub-header never rendered.
- `DocsAsideLeftBody.vue` — theme-subsection nav filter and the `ProIcon`
  badge.
- both `[...slug].vue` pages — `defineOgImage`; `nuxt-og-image` and the
  `DocsSatori` template are registered here, not in the theme. Rebased to
  take the layer's `USeparator decorative` a11y fix.
- `app/types/non-route-categories.ts` — a deliberate duplicate, because
  `modules/nonRouteCategories.ts` imports it by relative path at build time
  and that module has not moved into the layer yet.

Requires @uxfront/layer-docs@0.2.0, which is not published yet.

Refs UXF-119, UXF-3
@vercel

vercel Bot commented Jul 28, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
styleframe-dev Ready Ready Preview Aug 6, 2026 5:53am
styleframe-dev-storybook Ready Ready Preview Aug 6, 2026 5:53am

Request Review

@changeset-bot

changeset-bot Bot commented Jul 28, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: bbf8d10

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

It imported `~~/i18n/locales/en.json`, which moved into
`@uxfront/layer-docs` with the rest of the locale files, and it had zero
call sites — the layer's `useDocusI18n` is what the components actually
use. Its docblock also referenced `apps/shared/modules/config.ts`, a path
that does not exist in this repo, so it had been dead for a while.
The pin moved to ^0.2.0 with the layer extraction, but the lockfile still
resolved 0.1.0 because that release did not exist yet. It does now, so
the entry is regenerated against the registry — no local override.
@codecov

codecov Bot commented Aug 6, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@alexgrozav
alexgrozav merged commit 6041768 into main Aug 6, 2026
15 checks passed
@alexgrozav
alexgrozav deleted the agent/signal/31246d31 branch August 6, 2026 05:56

This branch was successfully deployed

2 active deployments
Preview – styleframe-dev — bbf8d10b Deployed Aug 6, 2026 by vercel[bot]
Preview – styleframe-dev-storybook — bbf8d10b Deployed Aug 6, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant